* * * * * * * * * * * * * * * # ##### # # # #### # # # # # * ##### ### * * # # # # #### # # * #### * * * * * * * * #### ### #### # # #### ### # # # # # # # # # # # * ### # # # # # ### #### * * # # # # # # # # # # # #### # #### # *# #### # # * * * * * * * * * * * * * ##### ##### ##### # ####* * # # # # # # # * # # # # # #* ### # # # # # # # # ##### ##### #### ### * * * * * * * * VERSION 1.0 Welcome to the JH'S C POWER TOOLS sharewhare manual. This manual is mainly designed for those c programers who wish to understand how to use the libarary's functions. If you want to know how the programs work or why they made the way they were you will need to get the expanded manual that comes with the registered version. The disks that were mailed to you should include the following: READx.EXE MENUx.LIB UTLx.LIB MOUSx.LIB KEYx.H MENx.H SHAPEx.H REGHELPx.TXT (This file) The x by each name is the version number. If you did not receive any of the following please contact me via my E-MAIL number or by regular mail and I will get a replacement copy to you ASAP. Thank you for you support. MENUx.C HELP SECTION: This is the menu help section. In this section I will go through each function one by one and explain how to call each function and what it returns. Before I start with the functions I am going to go over some basics that you will need to know in order to understand the functions. POINTERS: The usefulness of pointers come from the fact that in all C functions varibles are passed by value and since functions only recieve local varibles it can not change the original values that the varible represents. Pointers make this possible. Another use for pointers is the manipulating of an array by moving the pointers to its elements. A pointer is a varible that holds the address of an object (it "points" to the address in memory where the varible is stored.) DEFINATION OF POINTERS: All C varibles need to be defined and pointers are no different. Below are some examples of how to declare pointers: int *ptr; /* This is a pointer to an interger */ char *buffer; /* This is a pointer to a character */ char *buffer[]={ " This is a pointer ", " to an array of ", " characters ", ""}; In the last case: *buffer[1]=this is a pointer *buffer[2]=to an array of *buffer[3]=characters Any normal varible type that can be defined can also be defined as a pointer. HOW TO USE POINTERS: Example: 1) int x=1,y=2,z=3; 2) int *xx,*yy,*zz; 3) xx=&x; 4) yy=&y; 5) zz=&z; 6) printf(" x= %d\n y= %d\n z= %d\n",x,y,z); 7) printf(" *xx=%d\n*yy=%d\n*zz=%d\n",*xx,*yy,*zz); 8) printf(" &x=%u\n &y=%u\n &z=%u\n",&x,&y,&z); 9) printf(" xx=%u\n yy=%u\n zz=%u\n",xx,yy,zz); Alright you know that a pointer "points" to the address where a varible is stored. Right, good now here is where we start to get tricky. The '&' operater means "the address of" and * means "what is pointed to by." So in line 3 you would want to read it as "xx equals the address of x." There for you now know that the pointer xx is pointing to the varible x. If you follow that reasoning you could come up with the conclusion that in line 7 where we are printing out what is being pointed to by xx it should be the same value as x. Try to figure out what will be printed out before you run this program and then see if you are right. If so continue on. VARIBLES AND FUNCTIONS: Earlier we stated the fact that we use pointers to change the value of a varible in a function that was passed to it. With out pointers you could only return one varible from a function but with pointers you can change many varibles and have them stay changed when you leave the function. This section will show you how it is done. Example: 1) main() { 2) int x=0,y=0; 3) printf("x=%d/ny=%d",x,y); 4) change(&x,&y); 5) printf("x=%d\ny=%d",x,y); 6) } 7) change(int *x,int *y) { 8) *x=3; 9) *y=5; } This program will change the varible x and y to 3 and 5 respectively and they will remain changed when they return to the main function. Now we can return more than one varible from a function. When you pass an array of pointers to a function you don't have to pass each element of the array you can pass just the name. For example if you have an array of intergers defined as int *num={ 5, 10, 15, 20 } when you call the function you can call it like this 'function(num)' and the whole array will be passed. MISC POINTER FUNCTIONS: Say for example you have two pointers and you want to point to the same address: pointer1=pointer2 and it is done. Say you have a pointer to an array and you want to go to the next element in the array: pointer++ and it is done. Maybe you want to go to the previous element: pointer-- and it is done. POINTERS AND MY LIBARIES: I used a lot of pointers in my menu libary mainly because I am using direct memory addressing and it make it a lot easier to use pointer rather than varibles. I also tend to wnat to pass more than one varible back the the parent function. You have a basic understanding of pointers now so you should be able to understand must of what I am doing with them. For more infomation you can look an almost any C manual and they will give you about a ten to fifteen page lession on pointers. If you still have question fill free to contact me. INTERRUPTS: Interrupts are a neat and somtimes tricky part of your DOS and BIOS enviroment. If you are not sure what they are and how they work pick up almost any DOS reference manual and turn to the interrupt section and start reading you can find a LOT of interesting things that you can put in your programs that you throught were impossible to do. An interrupt is a signal to the processor from a program that tells the processor to temporarily suspend the current function that the CPU is working on and proform another task defined by the interrupt function number. Each interrupt function has a section of coded called an interrupt service routine that is memory resident just like any TSR program. So each time your program call an interrupt the interrupt service routine is run. In order for us to call an interrupt in C yor need to run one of the interrupt's call routines which are INT86(), INT86X(), INTDOS(), INTDOSX(). You will mainly want to use INT86. This function can be used to call any DOS or BIOS interrupt function while INTDOS can be used to call only DOS interrupt functions. The X that are part of two of the functions means that you have information in the segment registers. In order for any interrupt function to be called you need information in the registers below shows in example of a interrupt call. 1) union REGS regs; 2) regs.h.ah=2; 3) regs.x.bx=45; 4) int86(0x10,®s,®s); 6) go=regs.x.ax; This function does not do any thing I made up numbers as I went along so I strongly seggest you do not type this into you computer and run it. Line one defines the input and output from the interrupt function. the REGS in capital letters tell the compiler that the union regs will be used with an interrupt. regs.h.ah=2 moves the number 2 into the ah register regs.c.bx=45 moves 45 into the bx register. Line 4 calls interrupt 0x10 and line 5 moves whatever is in the ax register into the varible go. MENUx.C FUNCTIONS: FOREWORD: If you are making a program that has a lot of differnt menus you will need to make sure you free each pointer after you use it otherwise you will get a stack overflow error. If you have freed all of the pointers you think you possibly can and you still get an overflow error refer to your compilers manual on how to raise the stack settings. If for some reason these functions are not compatible with you compiler please contact me via E-Mail or regular mail and I will do my best to get you a version that will be compatible. These function were written in Quick C 2.5 which is compatible with MSC. I don't have access to Turbo C but as far as I know they should be compatible with that also. Hopefully before the next version is released I will be able to get Turbo C also so I can check the functions on that one also. From here-on-out when you see a number with an 0x in front of it that means it is in hex format. If their is nothing before it that means it is in dec format. MODE(INT MODE_CODE) This function sets the video mode to the mode defined by mode_code. This function calls the BIOS interrupt 0x10 (hex 10 dec 16) service 0 and passes it,via the al register, which mode you want the screen to be. All of the functions in this libary can use modes 0, 1, 2 and 3. I usually use mode 3 which is an 80x25 text mode with 16 colors. GET_CURR(),GET_CURC() These two functions get the current cursor position. Get_curr() returns the current cursor row and get_curc() returns the current cursor column. These functions call the BIOS interrupt 0x10 (just like the last function but instead of using service 0 it uses service 3.) In get_curr() it returns the value of register dh and in get_curc it returns the value of register dl. RETKEY(), INKEY(INT *ASCII) These two functions return the scan code of the key that was pressed. It will also wait for a key to be pressed. If you go into the read program under the reference section you will find a menu item called keyboard scan. This function will print out on the screen the scan code for any key you press. If you plan to use this function in you program I suggest you run keyboard scan and get the values for the keys you want to use. READ_CHAR(INT X,INT Y) This function reads the character at screen coordinates specified by x and y and returns it. I used the BIOS interrupt 0x10 service 8 to make this function work. This function is mainly used in the shadowing function to read the character at a certain location and then rewrite it with a different color. GOTO_XY(INT X,INT Y) This function moves the curser to the specified x,y coordinates on the screen. This function comes in very handy when you do a lot of printing and you need it at a certain location. An example of how to use this function: goto_xy(10,10);printf("* the star is located at coordinates 10,10); you mainly want to use this function with a printf statement. The write_char function below put characters at a certain location so you don't need to use this function when you use the other. This function uses BIOS interrupt 0x10 service 2 to do what it does. When ever possible I suggest you use the write_char() function because it is a lot quicker because it uses direct memory access rather than interrupts and you only need to call one function rather than two which you need to do with the goto_xy() function. SIZE(CHAR *STRING[],INT *X,INT *Y) This function determines the minimum horizontal and vertical size needed to print string[] to the screen. This function is used alot to determine how much space is needed to store the old screen before string[] is printed to the screen. This function returns the size of the array inside the x and y varibles so if you call this function like: size(buffer,hor,ver); The minumin horizontal size will equal hor and the minumin vertical size will equal ver. SAVE_BKG(UNSIGNED CHAR *BUFFER,INT STARTX,INT STARTY, INT ENDX,INT ENDY) RESTORE_BKG(UNSIGNED CHAR *BUFFER,INT STARTX,INT STARTY, INT ENDX,INT ENDY) These two functions either save the background before the menu is printed over it or restores the background after you are done with the menu. Both of these functions operate along the same principle with direct memory addressing. WRITE_CHAR(CHAR CHARACTER,INT X,INT Y,INT COLOR) This function writes a character and color to the screen at coordinates specified by x and y. COL_DISP(CHAR *TXT_BUFF[],INT X,INT Y,INT X1,INT Y1,INT COLOR) STR(CHAR *BUFFER,INT X,INT Y,INT COLOR) The str() is used by the col_disp(). I wil explain the str() function later in this section. The col_disp() function displays the information stored in the *txt_buff[], with the color specified by the color varible and puts it on the screen location specified by x,y. The first thing this function does is to determine how many lines are in the txt_buff this is done by subtracting y from y1 (y1 signifys endy) and puts it in the varible c. The next line in the program runs a loop c times. This lets the functions write every line to the screen. The third part of the program calls on function str() to break the string into individual characters and prints it on the screen. The function then increments y for the next line. MNU_BAR(INT ROW,INT COL,INT WIDTH,INT COLOR,INT COLOR1,INT DEPTH,INT SMENU) SLID_CUR(INT ROW,INT COL,INT WIDTH,INT COLOR,INT COLOR1,INT NUM,INT SMENU) These two functions operate on the same principle except one is for slide bars (The menus at the top of screens) and the other is for regular menus (The pull down menus.) Both of these functions need the same imfomation inputed to them the only difference is that the men_bar() has a interger named depth and the slid_cur has a interger named num. Both of these intergers mean the same thing (number of menu items.) The row and col (y,x I was kind of backward the day I made these functions so they are reversed) tells the function where the first menu item is located. The width tells the function how long to make the menu bar. The color and color1 defines the colors. Color should equal the color of the menu and color1 sould equal the color you want the bar to be. The smenu is the menu that you want the bar to start at usually this will be 1 (menu item 1.) Both of these functions return a 99 if the esc key was pressed or the row or col number if the return was pressed. DISP_BAR(INT ROW,INT COL,INT WIDTH,INT COLOR) This function is called by both functions mentioned above. It's purpose is to display the menu bar on the screen at location col,row with the color specified and the appropriate width. DISP_CURS(INT ROW,INT COL,INT COLOR,INT X) If x is one this function displays an arrow at video location col,row with the color specified. If x is zero this function erases what ever is at the screen location col,row. UNSIGNED INT *COL_MENU(CHAR *MENU[],INT STARTX,INT STARTY,INT ENDX,INT ENDY,INT COLOR,INT FRAME) COL_RES(UNSIGNED INT *BC,INT STARTX,INT STARTY,INT ENDX,INT ENDY) SCROLL(INT WAY,INT STARTX,INT STARTY,INT ENDX,INT ENDY,INT NUM,INT COLOR) CLS(INT COLOR) The function col_menu has to be defined as an unsigned int * because it returns a unsigned interger pointer that points to the address that the old screen was saved to. I am not going to go into these functions because I think that anyone that has got this for and understands everything so far should have little to no trouble figuring out how these function works. If you do have any problems please fell free to contact me via my E-Mail number and I will be more than happy to answer you questions. MOUS_CUR(INT ROW,INT COL,INT WIDTH,INT COLOR,INT COLOR1 INT DEPTH,INT WIDTH,INT SMENU) MOUS_SLID(INT ROW,INT COL,INT WIDTH,INT NUM,INT SMENU) BUTTON_REL() These three functions are mouse menu functions(). Look at the mous.lib section and the mnu_bar() and slid_bar() functions and try to figure out how they do what they do it will be a big help for when you try to do your own and if you have any questions fell more than free to contact me. MOUSEx.C FUNCTIONS: Refer to appendix b to get infomation on the mouse functions. The only mouse function that I will go indepth into here is the SETGRAPHPOINTER(). All of the mouse functions use DOS interrupt 0x33 to make the calls work. All of the mouse functions pass a varibles to a function called mouse(). The first varible is interrupt 0x33's service number and the varibles after that are the values to be passed back to the main function. Mouse() excepts four arguments that it places in pointers arg1 to arg4 and points the values into the registers (ax,bx,cx and dx.) Then it does the interrupt call and places the register values into the address of the arguments that were passed to it and returns. SETGRAPHPOINTER(UNSIGNED PTRMSK[],INT X,INT Y) The ptrmsk[] is an array of numbers that define the shape of the pointer. example the cross: HEX FORM BINARY FORM 0xfc3f= 1111110000111111 0xfc3f= 1111110000111111 0xfc3f= 1111110000111111 0x0000= 0000000000000000 0x0000= 0000000000000000 0x0000= 0000000000000000 0xfc3f= 1111110000111111 . . . 0x0000= 0000000000000000 0x0180= 0000000110000000 0x0180= 0000000110000000 0x0180= 0000000110000000 0x7ffd= 0011111111111100 . . . The first 16 elements are anded with the second 16 elements to give you the cursor you disire. There are more cursors in shape.h that you can use or you can add you own to it. If you have any problems please fell free to contact me and I will give you as much help as possible. ANDED: 0 AND 0 = 0 0 AND 1 = 0 1 AND 0 = 0 1 AND 1 = 1 Since the cursor isn't the size of one pixel we need to define which pixel will represent where the cursor is located that is where x and y come in they define the cursor's 'hot spot' or what part of the cursor represents where the cursor is. UTLx.LIB FUNCTIONS: The utl functions are just like the mouse functions, They all use interrupts to make the functions work. Refer to appendix c for information on what each function does. APPENDIX A: BRIEF FUNCTION DISCRIPTIONS FOR MENUx.C: MODE (INT MODE_CODE) This function excepts an interger mode_code. This function sets the video to the mode specified by mode_code. GET_CURR() This function excepts no values but returns the row that the cursor is at. GET_CURC() This function is just like the one above except it returns the column that the cursor is at. RETKEY() This function excepts no values but returns the scan code of a key pressed. It will wait for a key to be pressed before it returns to the program. GOTO_XY(INT X,INT Y) This function will put the cursor to the specified x,y corrdinates on the screen. SIZE (CHAR *STRING, INT *X,INT *Y) This function will return the maximum size of the buffer pointed to by *string (both length and width.) The function will put the size in the varibles x and y for return. SAVE_BKG( UNSIGNED CHAR *BUFFER, INT STARTX,INT STARTY ,INT ENDX,INT ENDY) This function will save a portion of the screen specifed by the startx, starty, endx and endy varibles. Before you run this function you need to allocate some memory. Below is an example of how to save the screen. unsigned int *pointer; char *buffer[]={ /*put menu here*/ int x,y,startx,starty; size (buffer,x,y); pointer=(unsigned int*)malloc (2*(x+2)*(y+2)); save_bkg(pointer,startx,starty,startx+x,starty+y); RESTORE_BKG(UNSIGNED CHAR *BUFFER,INT STARTX,INT STARTY INT ENDX,INT ENDY), This function restores the background saved by save_bkg(). You want to make sure you restore it to the same spot you saved it from. Also you need to free the pointer when you are done below is an example that goes along with the others. restore(pointer,startx,starty,startx+x,starty+y); free(pointer); WRITE_CHAR(CHAR CHARACTER,INT X,INT Y,INT COLOR) This function writes a character to the screen at coordinates x,y and puts it in the color specified by the varible color. COL_DISP(CHAR *BUFFER,INT X,INT Y,INT COLOR) This function displays a character buffer starting at coordinates x,y and in the color specified by the varible color. mem.h is some example of char buffers. MNU_CURS(INT ROW,INT COL,INT COLOR,INT DEPTH) This function will make a menu cursor for you starting at the specifier row ,column and will go down through depth number of menus. When I made these functions I was kind of backwards so remember row ins the y axis and col is the x axis. This function returns the y position of the cursor and breaks on either 'enter' or 'esc' MNU_BAR(INT ROW,INT COL,INT WIDTH,INT COLOR, INT COLOR1,INT DEPTH,INT SMENU) This function will make a bar rather than a cursor that was in the last function. Row,col,depth have the same roles as in the last function. Width is how wide you want the bar to be. Color is the color of the menu. Color1 is the color you want the bar to be. Smenu is which menu you want to start with. This function returns the y position of the cursor and breaks on either 'enter' or 'esc' SLID_CUR(INT ROW,INT COL,INT WIDTH,INT COLOR, INT COLOR1, INT NUM, INT SMENU) This function make a slide bar menu (instead of going un and down like the last two it goes left to right.) All the varibles have the same function as the ones in the last function. Num is the num of menus and width specifies the width of the bar as well as how far to jump each time you press the arrow keys This function returns the x position of the cursor and breaks on either 'enter' or 'esc' COL_MENU(CHAR *BUFFER,INT STARTX,INT STARTY,INT ENDX, INT ENDY,INT COLOR,INT FRAME) This function saves the screen, draws the menu with the specified color, draws a border (if you want one), draws a shadow (if you have a frame) and returns an unsigned int pointer all in one function. The border can be one of five borders specified by the frame varible: 0=no border or shadow 1=ÚÄÄÄ¿ and a shadow 2=ÖÄÄÄ· and a shadow 3=ÕÍÍ͸ and a shadow 4=ÉÍÍÍ» and a shadow In the next function is an example of haw to call this function COL_RES(UNSIGNED IN *POINTER,INT STARTX,INT STARTY, INT ENDX,INT ENDY) This function is used in conjunction with the one above. If you use the function above you need to use this one to restore the screen. Below is an example. unsigned int *p1; int startx,starty,x,y; char *buffer={ /*put menu here*/ size (buffer,x,y); p1=col_menu(buffer,startx,starty,startx+x,starty+y,20,4); /*menu cursor functions here*/ col_res(p1,startx,starty,startx+x,starty+y); free(p1); /*note you still have to free your pointer*/ SCROLL(INT WAY,INT STARTX,INT STARTY,INT ENDX,INT ENDY,INT NUM,INT COLOR) This function scrolls a part of the screen defined by startx,starty and endx,endy either up or down num number of times and with color defined by color. If you want the screen to scroll up way has to be equal to 1 and if you want it to scroll down way has to be 2. CLS(INT COLOR) This function clears the screen and put the color defined by the color varible. MOUS_CUR(INT ROW,INT COL,INT WIDTH,INT COLOR,INT COLOR1,INT DEPTH, INT SMENU) This function is basicly the same as mnu_bar() but instead of using keys for input it uses the mouse for cursor input. All of the varible are the same as mnu_bar. MOUS_SLID(INT ROW,INT COL,INT WIDTH,INT SMENU) This is the mouse version of slid_cur() function. They do pretty much the same thing except mous_slid uses a mouse while slid_cur uses keys for input. The varibles are the same as in slid_cur but with a few deleted. BUTTON_REL() Thing function returns when the mouse buttons are no longer pressed. APPENDIX B: BREIF FUNCTION DISCRIPTIONS FOR MOUSx.C: CURSOR_OFF() This function removes the mouse cursor from the screen. This function excepts and returns no values. CURSOR_ON() This function shows the mouse cursor on the screen. This function excepts and returns no values. RIGHTB_PRESSED() This function detects if the right mouse button was pressed. This function excepts no values but returns a 1 if the button was pressed or a 0 if the button was not pressed LEFTB_PRESSED() This function detects if the left mouse button was pressed. This function excepts no values but returns a 1 if the button was pressed or a 0 if the button was not pressed SET_MOUSE_POSITION(INT X,INT Y) This function sets the mouse cursor to the x y position on the screen This function excepts two interger for the x y coordinates but returns no values. MOUSE_POSITION(INT *X,INT *Y) This function returns the current position of the mouse cursor on the screen. This function excepts two pointers to intergers. The pointers recieve the current poition of the mouse cursor. MOUSE_MOTION(INT *X,INT *Y) This function returns a one in x if the mouse x value has changed since the last read. It also returns a one in y if the mouse y value has changed since the last read. MOUSE_RESET() This function resets the mouse to the default values and returns a 10 if mouse hardware are software is not installed. MOUSEXLIMIT(INT X1,INT X2) This function sets the limit (on the x axis) that the mouse can move. x1=minimum x value x2=maximun x value MOUSEYLIMIT(INT Y1,INT Y2) This function sets the limit (on the y axis) that the mouse can move. y1=minimum y value y2=maximum y value SETMICKY(INT X,INT Y) This function sets the micky to pixel ration. The range can be from 1-32767. Default values: x=8 y=16 DOUBLESPEED(INT X) This function sets the double speed threshold. default is 64 SETSENSITIVITY(INT XMICKY,INT YMICKY,INT DOUBLE) This function is a combination of the two above functions. This is to save steps in your programs. GETSENSITIVITY(INT *XMICKY,INT *YMICKY,INT *DOUBLE) This function returns the current vaules for mickys to pixel ratio and the double speed threshold. This function excepts three pointers to intergers. SETTEXPNTR(INT TYPE This function sets the text pointer to any ASCII character. This function excepts an interger from 0-255 and will change the text cursor to that ASCII character. SETGRAPHPNTR(UNSIGNED PTRMSK[],INT X,INT Y) This function changes the graphic cursor to the shape and color defined in PTRMSK[]. The file SHAPE.H has a few different shapes in it. APPENDIX C: BRIEF FUNCTION DEFINATIONS FOR UTLx.C: EQU_INFO (INT *EQU_RT) This function obtains the equipment list code stored in ROM bios. bit 0 = 1 if floppy drive is installed bit 1 = 1 if math co-processer is installed bit 2-3 = system board RAM size 00b 16KB, 01b 32KB, 10b 48KB, 11b 64KB bit 4-5 = initial video mode 01b 40X25 color, 10b color, 11b monochrome bit 6-7 = number of floppies installed 00b=1, 01b=2, 10b=3, 11b=4 bit 9-11 = number of RS232 ports installed bit 12 = 1 if game adapter installed bit 13 = 1 if internal modem is installed bit 14-15 = number of printers installed You would want to use this function if your program needs certain equipment in order to run. DOS_VER(INT *MIN,INT *MAJ,INT *OEM) This function returns the DOS major, minor and oem version that is currently running on your machine You would want to use this function if your program needs a certain DOS version or higher to run. MEMORY(UNSIGNED INT *MEM) This function returns the amount of convential memory available to dos. This function does not include extended or expanded memory. You would want to use this function if your program needs a minimum amount of memory to run. WARM_BOOT() This function does not proform a complete reboot process. What it does is proforms a partial memory check and resets the processor registers. GET_TIME(INT *HOURS,INT *MIN,INT *SEC,INT *HUNDREDTHS_SEC) This function obtains the system time and returns it to four interger listed above that can be displayed like this: hours:min:sec:hundredths_sec GET_DATE(INT *MONTH,INT *DAY,INT *YEAR) This function obtains the system date and returns it in three intergers listed above that can be displayed like this: month/day/year year is returned with values ranging from 1980 to 2099 ROTATE (UNSIGNED INT *VALUE,INT N) This function rotates the bit values of the giving number (value) n number of times. If n is negitive the bits rotate to the left If n is positive the bits rotate to the right This function works good when you need to find out what certain bit contain after you mask it INT_SIZE(UNSIGNED INT *SIZE) This function returns the bit size of the machine. You would want to use this function if you program requires a certain type of machine ie:80286 or higher SET_DAT(INT YEAR,INT MONTH,INT DAY) This function sets the date on the machine Year has to be between 1980 - 2099 SET_TIME(INT HOUR,INT MIN,INT SEC) This function sets the internal clock of the computer. Hour must be in the 24 hour format because the clock also moves the date when the time goes past midnight.